﻿<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <!-- Documenting T:NCoverExplorer.NAntTasks.NCoverExplorerTask-->
  <head>
    <meta http-equiv="Content-Language" content="en-ca" />
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <link rel="stylesheet" type="text/css" href="../style.css" />
    <title>&lt;ncoverexplorer&gt; Task</title>
  </head>
  <body>
    <table width="100%" border="0" cellspacing="0" cellpadding="2" class="NavBar">
      <tr>
        <td class="NavBar-Cell">
          <a href="">
            <b>NCoverExplorer.NAntTasks</b>
          </a>
          <img alt="-&gt;" src="../images/arrow.gif" />
          <a href="../index.html">Help</a>
          <img alt="-&gt;" src="../images/arrow.gif" />
          <a href="../tasks/index.html">Task Reference</a>
          <img alt="-&gt;" src="../images/arrow.gif" /> &lt;ncoverexplorer&gt;</td>
        <td class="NavBar-Cell" align="right">
                        v2.1.2.3433</td>
      </tr>
    </table>
    <h1>&lt;ncoverexplorer&gt;</h1>
    <p> NAnt task for automating NCoverExplorer.Console. Using this task you can merge coverage files from NCover, produce xml coverage reports for use with CruiseControl.Net, produce html report files directly, fail automated builds if coverage thresholds are not met and apply a range of detail to the reports produced such as sorting, filtering and coverage exclusions. </p>
    <h3>Parameters</h3>
    <div class="table">
      <table>
        <tr>
          <th>Attribute</th>
          <th style="text-align: center;">Type</th>
          <th>Description</th>
          <th style="text-align: center;">Required</th>
        </tr>
        <tr>
          <td valign="top">failCombinedMinimum</td>
          <td style="text-align: center;">bool</td>
          <td> Whether to fail the task if the minimumCoverage threshold is not reached on total coverage. NCoverExplorer console application will return exit code 3. </td>
          <td style="text-align: center;">False</td>
        </tr>
        <tr>
          <td valign="top">failMinimum</td>
          <td style="text-align: center;">bool</td>
          <td> Whether to fail the task if the minimumCoverage threshold is not reached on any module. NCoverExplorer console application will return exit code 3. </td>
          <td style="text-align: center;">False</td>
        </tr>
        <tr>
          <td valign="top">filter</td>
          <td style="text-align: center;">string</td>
          <td> The filtering if any to apply. Possible values are: "None" (default), "HideUnvisited", "HideFullyCovered", "HideThresholdCovered" </td>
          <td style="text-align: center;">False</td>
        </tr>
        <tr>
          <td valign="top">htmlReportName</td>
          <td style="text-align: center;">string</td>
          <td> The filename for generating an html report. </td>
          <td style="text-align: center;">False</td>
        </tr>
        <tr>
          <td valign="top">mergeFileName</td>
          <td style="text-align: center;">string</td>
          <td> The filename for the merge of the coverage xml files. </td>
          <td style="text-align: center;">False</td>
        </tr>
        <tr>
          <td valign="top">minimumCoverage</td>
          <td style="text-align: center;">float</td>
          <td> The minimum coverage percentage to be used with the failMinimum and failCombinedMinimum options. </td>
          <td style="text-align: center;">False</td>
        </tr>
        <tr>
          <td valign="top">outputDir</td>
          <td style="text-align: center;">string</td>
          <td> Gets or sets the output directory for the reports. </td>
          <td style="text-align: center;">False</td>
        </tr>
        <tr>
          <td valign="top">program</td>
          <td style="text-align: center;">string</td>
          <td> The name of the executable that should be used to launch the external program. </td>
          <td style="text-align: center;">False</td>
        </tr>
        <tr>
          <td valign="top">projectName</td>
          <td style="text-align: center;">string</td>
          <td> The project name to appear in the report. </td>
          <td style="text-align: center;">False</td>
        </tr>
        <tr>
          <td valign="top">reportType</td>
          <td style="text-align: center;">string</td>
          <td> The type of report to produce (note the "NCoverHTMLReport" requires NCover Enterprise Edition): "None" (default), "FullCoverageReport", "ModuleSummary", "ModuleMethodSummary", "ModuleNamespaceSummary", "ModuleClassSummary", "ModuleClassFunctionSummary", "ModuleMethodFunctionSummary" </td>
          <td style="text-align: center;">False</td>
        </tr>
        <tr>
          <td valign="top">satisfactoryCoverage</td>
          <td style="text-align: center;">float</td>
          <td> The satisfactory coverage percentage for display in the Sequence Point Coverage reports. </td>
          <td style="text-align: center;">False</td>
        </tr>
        <tr>
          <td valign="top">satisfactoryFunctionCoverage</td>
          <td style="text-align: center;">float</td>
          <td> The satisfactory coverage percentage for Functional Coverage reports. </td>
          <td style="text-align: center;">False</td>
        </tr>
        <tr>
          <td valign="top">showExcluded</td>
          <td style="text-align: center;">bool</td>
          <td> Determines whether to include the coverage exclusions in the report. The default is <b>true</b>. </td>
          <td style="text-align: center;">False</td>
        </tr>
        <tr>
          <td valign="top">sort</td>
          <td style="text-align: center;">string</td>
          <td> The sorting if any to apply. Possible values are: "Name" (default), "ClassLine", "CoveragePercentageAscending", "CoveragePercentageDescending", "UnvisitedSequencePointsAscending", "UnvisitedSequencePointsDescending", "VisitCountAscending", "VisitCountDescending", "FunctionCoverageAscending", "FunctionCoverageDescending" </td>
          <td style="text-align: center;">False</td>
        </tr>
        <tr>
          <td valign="top">xmlReportName</td>
          <td style="text-align: center;">string</td>
          <td> The filename for generating an xml report. </td>
          <td style="text-align: center;">False</td>
        </tr>
        <tr>
          <td valign="top">failonerror</td>
          <td style="text-align: center;">bool</td>
          <td> Determines if task failure stops the build, or is just reported. The default is <b>true</b>. </td>
          <td style="text-align: center;">False</td>
        </tr>
        <tr>
          <td valign="top">if</td>
          <td style="text-align: center;">bool</td>
          <td> If <b>true</b> then the task will be executed; otherwise, skipped. The default is <b>true</b>. </td>
          <td style="text-align: center;">False</td>
        </tr>
        <tr>
          <td valign="top">timeout</td>
          <td style="text-align: center;">int</td>
          <td> The maximum amount of time the application is allowed to execute, expressed in milliseconds. Defaults to no time-out. </td>
          <td style="text-align: center;">False</td>
        </tr>
        <tr>
          <td valign="top">unless</td>
          <td style="text-align: center;">bool</td>
          <td> Opposite of <code>if</code>. If <b>false</b> then the task will be executed; otherwise, skipped. The default is <b>false</b>. </td>
          <td style="text-align: center;">False</td>
        </tr>
        <tr>
          <td valign="top">verbose</td>
          <td style="text-align: center;">bool</td>
          <td> Determines whether the task should report detailed build log messages. The default is <b>false</b>. </td>
          <td style="text-align: center;">False</td>
        </tr>
      </table>
    </div>
    <h3>Framework-configurable parameters</h3>
    <div class="table">
      <table>
        <tr>
          <th>Attribute</th>
          <th style="text-align: center;">Type</th>
          <th>Description</th>
          <th style="text-align: center;">Required</th>
        </tr>
        <tr>
          <td valign="top">useruntimeengine</td>
          <td style="text-align: center;">bool</td>
          <td> Specifies whether the external program should be executed using a runtime engine, if configured. The default is <b>false</b>. </td>
          <td style="text-align: center;">False</td>
        </tr>
      </table>
    </div>
    <h3>Nested Elements:</h3>
    <!--Collection-->
    <h4>
      <a id="exclusions">
      </a>
            &lt;exclusions&gt;
        </h4>
    <div class="nested-element"> Coverage exclusions to apply. Refer to the examples for the exact syntax. The possible "type" attributes are "Assembly", "Namespace", "Class", "Method" and "FileName". <h5>&lt;exclusion&gt;</h5><div class="nested-element"><p> Represents a coverage exclusion for passing to NCoverExplorer.Console in the configuration file. </p><h3>Parameters</h3><div class="table"><table><tr><th>Attribute</th><th style="text-align: center;">Type</th><th>Description</th><th style="text-align: center;">Required</th></tr><tr><td valign="top">enabled</td><td style="text-align: center;">bool</td><td> Indicates if the exclusion is enabled. </td><td style="text-align: center;">False</td></tr><tr><td valign="top">isRegex</td><td style="text-align: center;">bool</td><td> Indicates if the pattern is a regular expression. </td><td style="text-align: center;">False</td></tr><tr><td valign="top">pattern</td><td style="text-align: center;">string</td><td> The pattern to match. </td><td style="text-align: center;">False</td></tr><tr><td valign="top">type</td><td style="text-align: center;">string</td><td> The exclusion type of Assembly, Namespace or Class. </td><td style="text-align: center;">False</td></tr></table></div></div><h5>&lt;/exclusion&gt;</h5></div>
    <h4>&lt;/exclusions&gt;</h4>
    <!--Collection-->
    <h4>
      <a id="moduleThresholds">
      </a>
            &lt;moduleThresholds&gt;
        </h4>
    <div class="nested-element"> Coverage exclusions to apply. <h5>&lt;moduleThreshold&gt;</h5><div class="nested-element"><p> A module threshold is used by the console application (only currently) to set coverage thresholds at a more granular level than just at project level. </p><h3>Parameters</h3><div class="table"><table><tr><th>Attribute</th><th style="text-align: center;">Type</th><th>Description</th><th style="text-align: center;">Required</th></tr><tr><td valign="top">moduleName</td><td style="text-align: center;">string</td><td> Gets or sets the name of the module. </td><td style="text-align: center;">False</td></tr><tr><td valign="top">satisfactoryCoverage</td><td style="text-align: center;">float</td><td> Gets or sets the coverage threshold for this module. </td><td style="text-align: center;">False</td></tr></table></div></div><h5>&lt;/moduleThreshold&gt;</h5></div>
    <h4>&lt;/moduleThresholds&gt;</h4>
    <!--Element-->
    <h4>
      <a id="fileset">
      </a>
                    &lt;<a href="http://nant.sourceforge.net/release/latest/help/types/fileset.html">fileset</a>&gt;
                </h4>
    <div class="nested-element"> Used to select the coverage xml files to merge into the report. To use a <a href="http://nant.sourceforge.net/release/latest/help/types/fileset.html">&lt;fileset&gt;</a>. <p /></div>
    <h4>
      <a id="fileset">
      </a>
                    &lt;/<a href="http://nant.sourceforge.net/release/latest/help/types/fileset.html">fileset</a>&gt;
                </h4>
    <!--Array-->
    <!--NestedElementArray=T:NAnt.Core.Types.Argument-->
    <h4>
      <a id="arg">
      </a>
                    &lt;arg&gt;
                </h4>
    <div class="nested-element"> The command-line arguments for the external program. <p> Represents a command-line argument. </p><h3>Parameters</h3><div class="table"><table><tr><th>Attribute</th><th style="text-align: center;">Type</th><th>Description</th><th style="text-align: center;">Required</th></tr><tr><td valign="top">dir</td><td style="text-align: center;">directory</td><td> The value for a directory-based command-line argument; will be replaced with the absolute path of the directory. </td><td style="text-align: center;">False</td></tr><tr><td valign="top">file</td><td style="text-align: center;">file</td><td> The name of a file as a single command-line argument; will be replaced with the absolute filename of the file. </td><td style="text-align: center;">False</td></tr><tr><td valign="top">if</td><td style="text-align: center;">bool</td><td> Indicates if the argument should be passed to the external program. If <b>true</b> then the argument will be passed; otherwise, skipped. The default is <b>true</b>. </td><td style="text-align: center;">False</td></tr><tr><td valign="top">line</td><td style="text-align: center;">string</td><td> List of command-line arguments; will be passed to the executable as is. </td><td style="text-align: center;">False</td></tr><tr><td valign="top">path</td><td style="text-align: center;">&lt;path&gt;</td><td> The value for a PATH-like command-line argument; you can use <code>:</code> or <code>;</code> as path separators and NAnt will convert it to the platform's local conventions, while resolving references to environment variables. </td><td style="text-align: center;">False</td></tr><tr><td valign="top">unless</td><td style="text-align: center;">bool</td><td> Indicates if the argument should not be passed to the external program. If <b>false</b> then the argument will be passed; otherwise, skipped. The default is <b>false</b>. </td><td style="text-align: center;">False</td></tr><tr><td valign="top">value</td><td style="text-align: center;">string</td><td> A single command-line argument; can contain space characters. </td><td style="text-align: center;">False</td></tr></table></div><h3>Nested Elements:</h3><!--Element--><h4><a id="path"></a>
                    &lt;<a href="http://nant.sourceforge.net/release/latest/help/types/path.html">path</a>&gt;
                </h4><div class="nested-element"> Sets a single command-line argument and treats it like a PATH - ensures the right separator for the local platform is used. <p /></div><h4><a id="path"></a>
                    &lt;/<a href="http://nant.sourceforge.net/release/latest/help/types/path.html">path</a>&gt;
                </h4><h3>Examples</h3><ul class="examples"><li><p> A single command-line argument containing a space character. </p><pre class="code">
&lt;arg value="-l -a" /&gt;
    </pre></li><li><p> Two separate command-line arguments. </p><pre class="code">
&lt;arg line="-l -a" /&gt;
    </pre></li><li><p> A single command-line argument with the value <code>\dir;\dir2;\dir3</code> on DOS-based systems and <code>/dir:/dir2:/dir3</code> on Unix-like systems. </p><pre class="code">
&lt;arg path="/dir;/dir2:\dir3" /&gt;
    </pre></li></ul></div>
    <h4>
      <a id="arg">
      </a>
                    &lt;/arg&gt;
                </h4>
    <h3>Examples</h3>
    <ul class="examples">
      <li> This example shows producing an xml coverage report at Module/Namespace/Class detail level for inclusion on a CC.Net build server. You would add a merge file task in the publishers section of your CC.Net project file to merge in this "CoverageSummary.xml" file so that it can be transformed by the NCoverExplorer xsl stylesheets you have copied into the CC.Net folder. Here we have set a satisfactory coverage threshold at 80%. <pre class="code">
    &lt;ncoverexplorer program="tools\ncoverexplorer\ncoverexplorer.console.exe" 
                    projectName="My Project"
                    outputDir="${build.reports}"
                    satisfactoryCoverage="80"
                    reportType="ModuleClassSummary"
                    xmlReportName="CoverageSummary.xml" &gt;
        &lt;fileset&gt;
            &lt;include name="coverage.xml" /&gt;
        &lt;/fileset&gt;
    &lt;/ncoverexplorer&gt;
    </pre></li>
      <li> This example shows producing an html function coverage report, excluding the test assemblies. The assemblies excluded are being displayed at the bottom of the report. Note also that this time the reportType is specified by its enum name rather than numeric value - they are interchangable. <pre class="code">
    &lt;ncoverexplorer program="tools\ncoverexplorer\ncoverexplorer.console.exe" 
                    projectName="My Project"
                    outputDir="${build.reports}"
                    satisfactoryCoverage="80"
                    reportType="ModuleClassFunctionSummary"
                    htmlReportName="CoverageSummary.html"
                    showExcluded="True" &gt;
        &lt;fileset&gt;
            &lt;include name="coverage.xml" /&gt;
        &lt;/fileset&gt;
        &lt;exclusions&gt;
            &lt;exclusion type="Assembly" pattern="*.Tests" /&gt;
        &lt;/exclusions&gt;
    &lt;/ncoverexplorer&gt;
    </pre></li>
      <li> This example shows producing an html module class summary coverage report with exclusions as above. This time we have added applying specific sorting and filtering criteria. This report will show all classes that do not have 100% coverage, sorted within their namespaces by descending coverage %. <pre class="code">
    &lt;ncoverexplorer program="tools\ncoverexplorer\ncoverexplorer.console.exe" 
                    projectName="My Project"
                    outputDir="${build.reports}"
                    satisfactoryCoverage="80"
                    reportType="ModuleClassSummary"
                    htmlReportName="CoverageSummary.html"
                    showExcluded="True"
                    sort="CoveragePercentageDescending"
                    filter="HideFullyCovered" &gt;
        &lt;fileset&gt;
            &lt;include name="coverage.xml" /&gt;
        &lt;/fileset&gt;
        &lt;exclusions&gt;
            &lt;exclusion type="Assembly" pattern="*.Tests" /&gt;
        &lt;/exclusions&gt;
    &lt;/ncoverexplorer&gt;
    </pre></li>
      <li> This example shows the merging capability to produce a consolidated merge file from multiple coverage test runs. The results are being stored in a single "MyApp.CoverageMerged.xml" file. Note that you could additionally apply coverage exclusions at this point. Merging files can be useful if your testing process requires multiple coverage runs and you want a single archive which consolidates the results. <pre class="code">
    &lt;ncoverexplorer program="tools\ncoverexplorer\ncoverexplorer.console.exe" 
                    outputDir="${build.reports}"
                    reportType="None"
                    mergeFileName="MyApp.CoverageMerged.xml" &gt;
        &lt;fileset&gt;
            &lt;include name="*.coverage.xml" /&gt;
        &lt;/fileset&gt;
    &lt;/ncoverexplorer&gt;
    </pre></li>
      <li> This example shows failing a build if the overall coverage % does not meet our threshold, without producing a coverage report. <pre class="code">
    &lt;ncoverexplorer program="tools\ncoverexplorer\ncoverexplorer.console.exe" 
                    projectName="My Project"
                    reportType="None"
                    minimumCoverage="80"
                    failMinimum="True" &gt;
        &lt;fileset&gt;
            &lt;include name="coverage.xml" /&gt;
        &lt;/fileset&gt;
    &lt;/ncoverexplorer&gt;
    </pre></li>
      <li> This example shows failing a build if either the overall coverage % does not meet our threshold, or if one of the individual module thresholds is not met. <pre class="code">
    &lt;ncoverexplorer program="tools\ncoverexplorer\ncoverexplorer.console.exe" 
                    projectName="My Project"
                    reportType="None"
                    minimumCoverage="80"
                    failMinimum="True" &gt;
        &lt;fileset&gt;
            &lt;include name="coverage.xml" /&gt;
        &lt;/fileset&gt;
        &lt;moduleThresholds&gt;
            &lt;moduleThreshold moduleName="MyApp.1.dll" satisfactoryCoverage="75" /&gt;
            &lt;moduleThreshold moduleName="MyApp.2.dll" satisfactoryCoverage="85" /&gt;
        &lt;/moduleThresholds&gt;
    &lt;/ncoverexplorer&gt;
    </pre></li>
      <li> This example shows using virtually the whole range of attributes. Shown below is failing a build if not reaching the overall or module level coverage thresholds. The results of merging multiple NCover files together are stored as a separate file. We are producing xml and html Namespace per module summary reports (with the exclusions show in the footer). Note that the module thresholds will also be used in the reports. The reports are sorted by name with no filter applied. We are excluding test assemblies and anything in a presentation layer namespace. <pre class="code">
    &lt;ncoverexplorer program="tools\ncoverexplorer\ncoverexplorer.console.exe" 
                    projectName="My Project" 
                    reportType="ModuleNamespaceSummary"
                    sort="Name"
                    filter="None"
                    outputDir="${build.reports}"
                    xmlReportName="CoverageSummary.xml"
                    htmlReportName="CoverageSummary.html"
                    mergeFileName="CoverageMerge.xml"
                    showExcluded="True"
                    satisfactoryCoverage="80"
                    minimumCoverage="80"
                    failMinimum="True"&gt;
        &lt;fileset&gt;
            &lt;include name="coverage.xml" /&gt;
        &lt;/fileset&gt;
        &lt;exclusions&gt;
            &lt;exclusion type="Assembly" pattern="*.Tests" /&gt;
            &lt;exclusion type="Namespace" pattern="MyApp.SomeNamespace" /&gt;
            &lt;exclusion type="Namespace" pattern="MyApp\.(\w*\.)?" isRegex="true" /&gt;
            &lt;exclusion type="Class" pattern="MyApp.SomeNamespace.SomeClass" /&gt;
        &lt;/exclusions&gt;
        &lt;moduleThresholds&gt;
            &lt;moduleThreshold moduleName="MyApp.1.dll" satisfactoryCoverage="75" /&gt;
            &lt;moduleThreshold moduleName="MyApp.2.dll" satisfactoryCoverage="85" /&gt;
        &lt;/moduleThresholds&gt;
    &lt;/ncoverexplorer&gt;
    </pre></li>
    </ul>
    <h3>Requirements</h3>
    <div style="margin-left: 20px;">
      <b>Assembly:</b> NCoverExplorer.NAntTasks (2.1.2.3433)
            </div>
  </body>
</html>